Registration Reminder


Registration


Help Writing Help Menus

Select this icon for information on how to use this online Help system.		The menu section graphically shows how information is organized in this book. If you prefer not to use menus, select the SKIP MENUS button at the bottom of the page.  To follow the menus, select a Help topic from the hotspots in the graphic:
Page 1 of 6 Menus


Contents Menu

		Select a Help topic from the hotspots in the graphic:
Page 2 of 6 Menus


Overview Menu
Overview

		Select a Help topic from the hotspots in the graphic:
Page 3 of 6 Menus


Designing Help Menu
Designing Help

		Select a Help topic from the hotspots in the graphic:
Page 4 of 6 Menus


How Do I? Menu

		Select a Help topic from the hotspots in the graphic:
Page 5 of 6 Menus


About Menu

		Select a Help topic from the hotspots in the graphic:
Page 6 of 6 Menus


Help Writing Help
 Help Writing Help (HWH)

Click on this icon for information on how to use this online Help system.		Choose from the following Help topics: Contents  Overview   Designing Help  How Do I?  About Help Writing Help
Page 1 of 2 HWH


 	Contents

		Choose from these Help Writing Help subtopics: Coding Help  Defining Objects  Generating Help  Thinking Smart   Troubleshooting Basics   Tracking Information
Page 2 of 2 HWH


 	How Do I?

		Here are some common procedures: Add Bitmaps to The HPJ File?  Add Bitmaps to The Topic File?  Create a Jump?  Create a Popup?  Create a Source File?  Create an HPJ File?  Keep Track of All This Information?  Make a Graphic a Hot Spot?  Quit Help Writing Help?  Troubleshoot a Compiler Error?  Work More Efficiently With My Word Processor?
Page 1 of 1 How


 	About Help Writing Help

		Here is some detailed information about Help Writing Help. Select from the following:      About Help Writing Help      Author Information      Trademark Information
Page 1 of 2 About


About Help Writing Help Information

Published by TechnoTrends

Written by Douglas W. Davis

Version 1.0 All rights reserved, December, 1993.


Author Information

		Douglas W. Davis is a consultant Technical Writer and training developer specializing in Windows online Help systems. Doug has been in the field of technical writing for over 10 years. He holds a Bachelors degree in Biology and Physical Science and a Masters Degree in Physical Science. He started his career as a teacher and progressed from secondary schools to college as an administrator of technical training programs with business and industry. During this phase of his career, his interests became focused on computers and computer applications. Moving with technology, he aptly found himself developing courseware and training for a large computer company. Learning PC skills, Doug became leader of a monthly publication after almost five years. New opportunities in another company provided the chance to keep pace with the evolving PC marketplace. Starting in an internal consulting group, Doug wrote a variety of hardware and software documentation, including some training materials. Never far from a PC, Doug honed his skills to move into an internal start-up operation where he learned Microsoft Windows Help.
Page 1 of 2 Author


Author Information Continued
Author Information (Continued)

		He became a consultant and has helped conceive, design, and implement innovative online Help systems for several companies in the greater Boston area.  Doug publishes TechnoTrends, a quarterly newsletter targeted to technical writers. The focus of the newsletter was geared to PCs and Macs with a recent change towards Windows online Help. "This book has been easier to do thanks to some highly qualified friends. My special thanks to:" Nick Bulka - Programmer who helped me create the installation procedure for this book. Jennifer Qualey - Graphic artist and icon designer who provided suggestions on formatting and icon design. She makes this stuff look easy! Dave Martin - Who helped test and review the book. Gloria Sciuto Nichols - Editor who performed valuable edits and testing throughout the book writing process. Without her assistance, this book would never have the polish it does!
Page 2 of 2 Author


Trademark Information

		Windows [image] is a registered trademark of Microsoft Corporation. IBM [image]  is a registered trademark of the International Business Machines Corporation. Microsoft [image] is a registered trademark of the Microsoft Corporation.
Page 1 of 1 Trademark


Quit Help Writing Help

		To exit Help Writing Help: Mouse: Select Exit from the File menu. Select Close from the Control menu. Keyboard: Press ALT + F + X. Press ALT + SPACE + C.
Page 1 of 1 Quit


 Expanded Help Contents

Click on this icon for information on how to use this online Help system.		Choose from the following expanded Help topics: Contents  Coding Help  Coding Sequences to Follow   Understanding Syntax Rules  Working With Graphics  Defining Objects  Symbols  Terms  Format Control Codes  Generating Help  The Help Project (.HPJ) File  The Source File(s)  The Help Compiler  Thinking Smart  Bookmarking Topics  Using Drag and Drop  Using Glossaries   Using Macros  Using Outlining  Using Styles and Templates  Using the Time and Date Stamp  Saving Work  Troubleshooting Basics   Syntax Errors  Reported Formatting Errors  Visually Detected Errors  Duplicate or Lost File Errors  Miscellaneous Errors  Tracking Information  What to Track  Methods of Tracking  Archiving Information  Overview  Summary  Audience  The Goal of Help Writing Help  Requirements  Designing Help  Defining and Questioning  Generating and Refining  Finalizing  Planning the Architecture   Visualizing the Help Architecture   Planning Browse Sequences  Determining Preliminary Linkages  Determining the Degree of Context Sensitivity  Writing Module Summaries  Implementing  Structuring Process  Formalizing Help Conventions   Coordinating Tasks  How Do I?  Add Bitmaps to The HPJ File?  Add Bitmaps to The Topic File?  Create a Jump?  Create a Popup?  Create a Topic File?  Create an HPJ File?  Keep Track of All This Information?  Make a Graphic a Hot Spot?  Quit Help Writing Help?  Troubleshoot a Compiler Error?  Work More Efficiently With My Word Processor?  About Help Writing Help


How to Use This Help System

		This section describes how to use the Help Writing Help system. It outlines some of the features and describes the conventions used, as well as how to navigate around the system. Display The interface for Help Writing Help offers several ways of using the system. It starts by offering a series of menus containing hotspots that point to the topics in Help. Once you are familiar with the system, you can skip the menus and use either the short or expanded table of contents (TOC). Using the short version of the TOC, you will have a few extra clicks to reach the information being sought. If you use the expanded TOC, you can reach Help information more directly without the inconvenience of having to scroll a long listing of topics. Navigation Help Writing Help offers easy navigation throughout the system. In addition to Browse buttons (<< and >>) to flip pages in the Menu Bar, there are additional devices at the bottom of the pages. Select the green right arrow to continue to the next page.
Page 1 of 4 How To Use


How to Use Help Continued
How to Use Help (Continued)

		Conventions Used Here are some of the typical conventions used:  Expands the table of contents to a full listing of topics  Contracts the TOC listings to a reduced set of topics  Omits the menus and jumps to the collapsed TOC  Activates the menus
Page 2 of 4 How To Use


How to Use Help Continued 2
How to Use Help (Continued)

		Returns to the page that called this topic  Jumps to the next page of this topic irrespective of any browse sequences used  Jumps back to the previous page of this Help topic  An icon that displays in the margin for a jump and with text in a popup that indicates a note of additional information  An icon that displays in the margin that indicates other relative topics
Page 3 of 4 How To Use


How to Use Help Continued 4
How to Use Help (Continued)

		An icon that displays in the margin for jumps and in text in popups that indicates a procedure or series of steps to follow Format Help Writing Help is formatted similar to a hardcopy book. You will see a large gutter of blank space to the left of your display. Page numbers appear at the bottom left of the display, and navigational devices appear on the bottom right of the screen. This layout will enable you to scan the screen and to determine if it contains the information you want without having to read the whole screen first.  Occasionally, there will be information placed in the gutter. Typically, it will be in the form of a note or graphic. Rarely, will this information contain hotspots. When it does, you will be notified of their presence.
Page 4 of 4 How To Use


Coding Help

		Adding control codes to source files is coding Help. This section describes basic techniques to prepare the Help system for the compiler. It includes: Coding Sequences to Follow   Understanding Syntax Rules  Working With Graphics
Page 1 of 12 Code


Coding Sequences to Follow

In building the Help system, there are several steps to follow in this sequence:


Understanding Syntax Rules

		Windows Help syntax is not difficult to learn. There are two types of syntax rules to learn, as follows: Syntax for Coding Topics  Syntax for Coding Buttons
Page 2 of 12 Code


Syntax for Coding Topics

		Here are the syntax rules for coding Windows Help topics:
	Rule Page Breaks Context Strings Footnotes	Description Each Windows Help topic requires its own page. This includes popups. Separate all topics with a hard page break. Example of page breaks.   Each context string (link) that calls another topic must appear in the source file as hidden text. Example of a context string:  The word processor must be able to create definable footnotes. (Footnotes other than those that are numbered). You need to create footnotes with dollar signs ($), pound signs (#), plus signs (+), and uppercase K (K) as the footnote symbols. Example Footnote:
Page 3 of 12 Code


Coding Topics Continued
Coding Topics (Continued)

	Here are the remaining syntax rules for coding Help topics:
	Index    Jumps    Popups	The first topic listed in the HPJ file represents the application index. (Index here is Windows terminology). The compiler uses the first file listed in the HPJ file to run the build process. It contains the table of contents for the Help system. This can be either part of a larger source file or a separate file by itself. Example Index:  One topic can call another topic in another section of the Help system. Hard code jumps with hidden text after double underlined or strike through text. Example Jump:  A topic can call a definition or example to illustrate a point. These are called popups. Hard code popups with hidden text after single underlined text. Example Popup:
Page 4 of 12 Code


Example of page breaks:

Here is how topics appear with hard page breaks in Word for Windows:


Example of a Context String:

Here is a typical example of how a context string appears in the source file that calls another topic:


Example Footnote:

Here is a typical footnote:


Example Index:

Here is an example of an index as the first topic in a file:

User's View

Writer's View


Example Jump:

Here is a typical example of a jump:


Example Popup:

Here is a typical popup:


Creating a Jump

(Making text a hotspot)

To create a jump for a topic, follow these steps:

1.	Open the source file to the location of the jump text (hotspot text).

2.	Highlight the hotspot text and format it as double underscore text.

3.	Immediately after the hotspot text type the context string.

4.	Highlight the context string and format it as hidden text.

5.	Compile the Help file and test the results.


Creating a Popup

(Making text a popup)

To create a popup for a topic, follow these steps:

1.	Open the source file to the location of the popup text (hotspot text).

2.	Highlight the hotspot text and format it as single underscore text.

3.	Immediately after the hotspot text type the context string.

4.	Highlight the context string and format it as hidden text.

5.	Compile the Help file and test the results.


Adding a Bitmap to the HPJ File

To add a bitmap to the HPJ file, follow these steps:

1.	Open the HPJ file and locate the [BITMAP] section. If there is no [BITMAP] section, make one by typing "[BITMAP]."

2.	Enter the name(s) of the bitmap(s) for your Help system. Include path names. For example:

C:\bitmap\FIRST.BMP

C:\bitmaps\MYPIC.WMF

C:\bitmap\MYSHG.SHG

3.	Save the HPJ file.


Syntax for Coding Buttons

	The most common buttons included with Help systems are as follows:
	Button Contents   Search	Description The Contents button is the table of contents (TOC) for the Help system. The Contents button lists the broad categories of Help topics available. It serves as one point of entry for users. In the HPJ file, if you specify a source file as the index or list the file first under [FILES], it is treated as the Contents button during the build. The Search button gives the user several points of entry to locate a specific topic. This button is analogous to an index in a book. Hard code the Search Button using keywords in the footnote section of each topic respective source files.
Page 5 of 12 Code


Coding Buttons Continued
Coding Buttons (Continued)

	Here are the remaining, common buttons used in online Help systems:
	Browse    Other	The Browse button allows the user to move through a group of related topics defined by the Help writer. Example: Creating a Browse Sequence.   You can create other buttons, such as a Glossary button or Error Messages button by using advanced programming techniques. For more information on creating new buttons, refer to the appropriate development kit.
Page 6 of 12 Code


Coding the Search Button

 Follow these steps to assign a keyword to a Help topic:

1.	Open the source file and locate the topic heading to index.

2.	Insert uppercase K as the special footnote. In this example, the entry appears: K Search Button

3.	Type the keyword as the footnote. You can use more than one keyword if you separate them with a semicolon (;). For example:

K Keywords, Using Search; Defining, keywords; Search button, keywords

4.	Save the source file in RTF format to use with the Help compiler at the DOS level.

As the user performs a search on these keywords, the respective topic title name (in this example: Search Button) appears in the search dialog box. Users can now search on:

Defining, keywords

Keywords

Search button, keywords

Using Search


Modify the HPJ file

		Follow these steps to modify the HPJ file for Browse sequences: 1. Open the HPJ file with the appropriate text editor. 2. After the [OPTIONS] section, create a new section called the [CONFIG] section . 3. Type BrowseButtons ( ) under the [CONFIG] section. 4. Save the file and run the Help compiler after modifying the source file. After the build process, the Help system contains the next (>>) and previous (<<) browse buttons. These buttons will become active when the user selects the appropriate browse group. Example: Creating a Browse Sequence
Page 1 of 1 HPJ File


Creating a Browse Sequence:
Creating a Browse Sequence

Number sequences in large enough steps to accommodate adding other topics in the sequence later. Usually, incrementing by 10 works well.		Summary  Select the group of topics for the browse sequence. Modify the source file by adding special footnotes and save it in RTF format. Next, modify the HPJ file  by adding a new section. Assign a special unique name for the browse sequence.  Procedure Determine which topics need browse sequences. Open the appropriate source file and begin with the first topic in the grouping. 1. Create a special footnote and designate it as "+." 2. Assign a group name . For example, MENU. End it with a colon (:) 3. Assign an arbitrary number  immediately after the name, such as 010. Include the leading zero. This allows numbers from 1 to 999.  4. Move to the second topic in the grouping and repeat step one above. 5. Assign the group name and increment the number by 10.
Page 1 of 2 Browse


Browse Sequence Continued
Browse Sequence (Continued)

		6. Repeat these steps for all topics in the grouping and save edits in RTF format. 7. Open the HPJ file and create a new section following the [OPTIONS] section named [CONFIG]. 8. Type BrowseButtons() under the CONFIG section . 9. Re-compile the Help file.
Page 2 of 2 Browse


Example: Assign Group Name

The example appears:

+MENU:


Example: Arbitrary Number

The example appears:

+MENU:010


Example: Increment by 10

The example appears:

+MENU:020


Example: CONFIG Section

Here is how it should look:

[OPTIONS]

[CONFIG]

BrowseButtons()


Working With Graphics

		This section describes how to enhance the Help system by using graphics. Graphics can contain hotspots used as hypertext links to other topics. Topics for this section include: Adding Bitmaps to Source Files  Making Icons Hotspots  Using The Hotspot Editor (SHED.EXE)  Cautions
Page 7 of 12 Code


Adding Bitmaps to Source Files

		Windows Help restricts file types for display in Help. Currently, the Help compiler supports bitmaps, metafiles, and hypergraphics (SHG).  The best way to add a graphic to a source file is to reference it and not actually place the graphic in the file. This saves a tremendous amount of file space and is the most economical way of using graphics. As a general rule, always reference graphics unless they are quite small.  Here are the three ways of coding graphics by referencing.
Page 8 of 12 Code


Example: Referencing Bitmaps

Example: Referencing Graphics

Here are the three ways to reference graphics:

Type	Description
{BMC YOURBMP.BMP}	This places the bitmap near the center of the space provided. Use this most often and when placing small graphics between words.
{BML YOURBMP.WMF}	This places the metafile to the left-most part of the line.
{BMR YOURBMP.SHG}	This places the hypergraphic to the right-most part of the line.


Making Icons Hotspots

		Icons require little space. They are the exception to the rule regarding referencing graphics. This procedure requires icons to be in bitmap format. To make an icon a hotspot, follow these steps: 1. Locate the appropriate position in the source file for the icon. 2. Insert a icon using the method of inserting a bitmap for your specific word processor. 3. After placing the icon, follow these directions: Jump Hotspot Double underline (strike through for some word processors) the graphic and add a context string next to it using hidden text. Popup Hotspot Single underline the graphic and add a context string next to it using hidden text.
Page 9 of 12 Code


Example: Double Underline Icon

Here is an example of how to double underline an icon:

HIDDEN_TEXT_CONTEXT_STRING


Example: Single Underline Icon

Here is a typical example:

HIDDEN_TEXT_CONTEXT_STRING


Using The Hotspot Editor (SHED.EXE)

Know the names of context strings to complete the Attributes section.  The graphics used in this technique cannot be text line edited. The graphic saved using the Hotspot Editor should be final copy, not requiring any further edits. This problem is a restriction of the Editor.		Use the Hotspot Editor to make multiple hotspots inside the same graphic. This means there can be multiple jumps and popups inside the same graphic. Graphics used for this purpose enlarge greatly. Use them appropriately throughout the Help system. The process is as follows: 1. Running the Hotspot Editor, open the bitmap file of choice. 2. Using the mouse, draw the hotspot locations inside the graphic. 3. Select Attributes from the Edit menu and describe the characteristics for each hotspot.  4. Save the file as a hypergraphic.  For more information on using the Hotspot Editor, refer to the Hotspot Editor documentation.
Page 10 of 12 Code


Cautions

	Here are a few problems to consider when using graphics:
	Problem Out of Memory Errors	Description This problem occurs when there are too many graphics in the Help system. Solution: The PC may not have enough free lower memory to allocate the buffers required during the build process. Use the MS-DOS command MEM /C and determine how the PC allocates memory. One solution to free up memory is to comment out device drivers in the CONFIG.SYS file. Another approach is to run the compiler using high memory. Check the Windows documentation for more information on tuning PC memory.
Page 11 of 12 Code


Cautions Continued
Cautions (Continued)

	File Size Increases	Using hypergraphics (one large bitmap broken into several Hotspots) can greatly increase the Help file size.  Solution: If file size is a restriction, consider reducing the number of bitmaps or hypergraphics in the source file. Also remember to use the Hotspot Editor to reduce bitmap file size. Using too many color bitmaps (or saving them as 256 bit graphics) causes large help files. Windows Help only supports 16 color graphics. How many is too many is up to the size limitation placed on the Help system. Solution: Again, if file size is a restriction, reduce the number of color graphics in the Help system. Monochrome bitmaps work just as well and reduce file size considerably.
Page 12 of 12 Code


Defining Objects

		Windows Help describes a variety of objects and uses specific terminology. This section defines these terms and includes the following: Symbols  Terms  Format Control Codes
Page 1 of 6 Define


Symbols

	There are 4 symbols Windows Help uses to program Help topics. They are as follows:
	Symbol # pound sign $ dollar sign + plus sign Uppercase K	Description Identifies a unique link to a specified topic. These links are called Context Strings. Defines a topic title. This is optional if the topic is used as a popup. Titles appear in a list box when you press Search. Defines optional groupings of help topics. These are associated with the Browse buttons in the button area. Indicates the word or phrase is a keyword in Windows Help. Use keywords (optional) to search for specific Help topics. They are the same as index entries in a book.
Page 2 of 6 Define


Terms

		Here is a list of some common terms used in Help: Bitmap Browse Sequence Build Process Buttons  Context Strings Help Compiler  Help File (HLP) Help Project File (HPJ)  Help Topic  Help Tracker  Hidden Text  Hotspot  Hotspot Editor  Hypergraphic
Page 3 of 6 Define


Terms Continued

		Icon  Jump Keywords  Metafile  Microhelp  Popup RTF File  Topic File
Page 4 of 6 Define


Buttons

		Windows online Help contains a row of Help buttons along the top of the Help window. The most common buttons in Help are as follows: <Previous Browse Button  >>Next Browse Button  Back Button Contents Button Glossary Button  History Button  Search Button  Specially-Named Buttons
Page 5 of 6 Define


Bitmap

A bitmap is a graphic in Windows Bitmap format BMP. Bitmaps can be either small icons or large images that cover most of the screen display. Bitmaps often appear as hotspots. They can also have hotspots coded inside of them. Bitmaps are optional in Help systems.


Browse Sequence

A browse sequence is an optional grouping of related topics linked to display one after another in the Help system. They allow the user to see topics grouped or clustered in families or close associations. When browse sequences are present in Help, they appear as Browse buttons in the button portion of the Help Window.


Build Process

The build process invokes the Windows Help compiler to generate a Windows Help (HLP) file. This takes place at the MS-DOS command line, not in Windows. The process can generate a variety of error messages that need correcting when they occur.


Context Strings

A context string is the link that joins another topic or graphic to form hypertext connections. Sometimes referred to as symbolic references, context strings are the main building blocks of the Help system. All context strings are hard coded in the source file as hidden text. Context strings need to be tracked and maintained whenever the source file changes.


Help Compiler

The tool that transforms the source and project files into a Help (.HLP) file for the application.


Help File (HLP)

The Help file (.HLP) is the output of the Windows Help compiler for Windows online Help.


Help Project File (HPJ)

The Help Project File (HPJ) is the file used by the Windows Help compiler to drive the sequences, to include files, and to give special directions during the build process. It lists the files and graphics used and specifies how to build the .HLP file. The HPJ file is in ASCII format and is mandatory to generate Help.


Help Topic

A Help topic is the individual subject matter that the Help system explains. The number of topics depends on the complexity of the application and on the Help system. Help topics can be printed from within the Help system.


Help Tracker

The method employed to remember information used in the Help system, including names of context strings.


Hidden Text

Cloaked text used to code Help jumps and popups in a Help system.


Hotspot

The pointer changes shape when it passes over a hotspot on the screen. This indicates that there is more information or a graphic to further illustrate a topic.


Hotspot Editor

This is the tool to make various parts of a graphic into hotspots. This tool requires knowledge of the context strings for each topic defined.


Hypergraphic

A hypergraphic is usually a bitmap or metafile with hotspots added to it from the Hotspot Editor. Hypergraphics are optional. For more information, refer to the appropriate Hotspot Editor documentation.


Icon

An icon is a bitmapped image created using a paint program. Icons measure 32 x 32 pixels.


Jump

A jump is a hypertext link to a new location within the Help system. It enables users to move to new topics and get more information from the Help system.


Keywords

Keywords are words associated with the Search button. They serve as index entries and enable users to locate specific information.


Metafile

A metafile is an image defined by coded shapes and lines. Metafiles have the file extension .WMF. They are a form of vector graphics and are device independent.


Microhelp

Some Windows applications provide additional information on the Status bar at the bottom of the application. This is called microhelp. It gives a brief description of the button or function that has focus.


Popup

A popup is a small, temporary window that appears inside the Help window. The user accesses popups by clicking the mouse button or pressing Enter on green underscored words or phrases. Popups show definitions, graphics, or brief examples. Popups cannot be printed.


RTF File

RTF stands for rich text format. RTF files contain the syntax and necessary mark-up for the compiler to interpret various formatting and document information during the build process. Use one of the professional word processors to automatically convert document formats into RTF formats, such as Word for Windows [image].


Topic File

The topic file is the source file and it contains the various topics, jumps, popups, and links to the Help system. Topic files can be printed, and there can be more than one topic file in a Help system.


Contents Button

This button allows you to view the Help Contents for your specific application. The Contents button is not optional, and it is analogous to a book table of contents (TOC).


Search Button

This button allows you to locate information about various topics using a list of pre-recorded keywords. You can only search using keywords within the Help system listings. The Search button is not optional.


Back Button

This button allows you to view previously viewed Help topics. This button retraces your steps in reverse, chronological order. Each press of the button traces back one step at a time. The Back button is not optional.


History Button

This button allows you to view the sequential listing of every Help topic you have accessed during the current Help session. It is useful for returning to a previous topic quickly. The History button is not optional.


Glossary Button

The Glossary button allows you to open up a mini-dictionary in the application. The Glossary button is optional and requires special coding and configuration in the HPJ file.


<< Previous Browse Button

The Previous Browse button allows you to redisplay the previous Help topic viewed. These buttons are inactive when grayed out. The Browse buttons are optional and require special coding and configuration in the HPJ file.


>> Next Browse Button

The Next Browse button allows you to redisplay the previous Help topic viewed. These buttons are inactive when grayed out. The Browse buttons are optional and require special coding and configuration in the HPJ file.


Specially Named Buttons

You can create your own custom buttons at the top in the Help window by using Help compiler macros and by modifying the HPJ file. For example, you may want to create a button for error messages.


Format Control Codes

		There are several word processing formatting control codes used to generate Windows Help. They are as follows: Footnotes  Underlining  Double Underlining or Strike Through  Hidden Text Control Code
Page 6 of 6 Define


Footnotes

Windows Help uses custom footnotes with special characters and symbols to code Help topics, jumps, and popups. You can use any word processor that allows custom footnotes and save files in RTF format to create Windows Help source files. Custom symbols include #, +, K, and $.


Underlining

Underlined text creates popups in Help systems. Words underlined become hotspots when linked with context strings in hidden text. Underlining indicates that the selected text or graphic is linked to a popup with more information.


Double Underlining/Strike Through

Double underlined or strike through text creates jumps to other topics. It is used in the source files along with hidden text.


Hidden Text Control Code

Hidden text is text that can be viewed in the source file but not seen on the screen in the Help system. Jumps, popups, and all links require hidden text in order to make the hypertext links work.

Terms are underscored (single for popup or double for jump) followed by hidden text containing the context string.


Overview

		Help Writing Help is written using a different approach for a targeted audience. Overview topics include the following: Summary  Audience  The Goal of Help Writing Help  The Purpose Of Help Writing Help  Requirements
Page 1 of 9 Overview


Summary

		The summary topics include: The Purpose of Help Writing Help   What Is Help Writing Help?  3 Kinds of Help
Page 2 of 9 Overview


Three Kinds of Help
3 Kinds of Help

		There are 3 kinds of Windows Help you can provide in a Help system. They are as follows: F1 Help  Mouse Button Help   SHIFT + F1 Help
Page 3 of 9 Overview


F1 Help

You can access online Help from anywhere in the application by pressing F1.  This activates the online help menu and table of contents (TOC). Generally, this menu lists the Contents, Commands, Procedures, and relative information regarding the version and release of the application. This is the keyboard equivalent to access online Help.


Mouse Button Help

Using the mouse to point and click to various menus and parts of the screen, you can access online Help. The information provided by this access method is identical to pressing F1.


SHIFT + F1 Help

Windows Help allows you to create context-sensitive Help using keys in sequence. You can obtain information relating to parts of the screen or from dialog boxes. To activate context-sensitive Help, you press SHIFT + F1 simultaneously. The mouse pointer changes to an arrow with a question mark.

Context-sensitive Help is not as common in all applications because it involves greater efforts by the Help writer and software developers. It usually offers greater levels of Help in places, such as fields in individual dialog boxes.


Audience

		Help Writing Help is for technical writers and developers who have to write Help systems. It requires no formal programming background. However, the process of creating and generating Help files is similar to the programming process. Writers have to code source files, use a compiler, test the resultant Help file, and debug identified problems. Audience Prerequisites
Page 4 of 9 Overview


Audience Prerequisites

		You should be familiar with MS-Windows Version 3.1 (including setting up icons in the Program Manager) and know how to run the Windows Help compiler. You should have a solid knowledge of PCs, MS-DOS, batch files, ASCII editors, and familiarity with a professional PC word processor. Other required skills include knowledge of PC screen capture programs, PC graphics editors, knowledge of macros, and use of document styles and style guides (writing is assumed).  Any understanding of online information design is helpful.
Page 5 of 9 Overview


The Goal of Help Writing Help

		The goal is to reduce the amount of time required to learn the basics of creating a Help system. Often, Help authoring tools make is easy to generate Help but not to modify and customize Windows Help. It does not matter which tools you use to develop Windows online Help files, if any. The primary goal of Help Writing Help is to make learning, developing, writing , and tracking Windows Help easier for writers and software developers who write Help.  The Purpose of Help Writing Help
Page 6 of 9 Overview


The Purpose of Help Writing Help

		Most Windows online Help information available is scattered in a variety of places (including CD ROM) and not targeted for technical writers. The intention of Help Writing Help is to make this information easy to access in a central place as an online reference. Goal of Help Writing Help
Page 7 of 9 Overview


What Is Help Writing Help?

		Help Writing Help is a book designed specifically for writers who have to design and develop Windows online Help for third-party applications. It is written from the writer's point of view and contains helpful information on how to accomplish this task. It runs under Windows as a Help file. This book is meant to be used as an online reference to use in Windows while writing a Help system.
Page 8 of 9 Overview


Requirements

		There are 3 requirements for generating a Windows online Help system for your application. They are as follows: Hardware Required  Software Required  Tooling Required
Page 9 of 9 Overview


Hardware Required

You can generate Windows online Help using a variety of hardware. Here is a list we recommend that represents the minimal hardware:

System Requirements

20 MHz IBM [image] compatible computer

80 MB of hard disk space

8 MB RAM

3 1/2 inch floppy drive

Mouse or trac ball or pointing device

VGA color monitor


Software Required

You need the following software to generate a Windows Help file:

Software Requirements

Window's SDK Version 3.1 or greater

Windows Version 3.1 or greater

A screen capture program


Tooling Required

In addition to the basic software, you may want to have some of the following:

Database or spreadsheet for tracking

Screen capture program

Graphics viewer for metafiles and bitmaps


Generating Help

		There are three essentials to generate Windows Help. They are as follows: The Help Project (.HPJ) File  The Source File(s)  The Help Compiler  Optional Files
Page 1 of 20 Generate


The Help Project (.HPJ) File

		The HPJ file controls the build process. It contains various sections (nine possible) that provide information on how to create the Help file. It tells the Help compiler what to include in the build. It is important to know how to create and modify this file. Whenever new source files and graphics are added, the HPJ file needs updating before compiling. The Help Project File must have the extension .HPJ in order for the Windows Help Compiler to recognize it. It must also be an ASCII text file with no formatting present.  The HPJ file name and the resulting Help (.HLP) file name are the same - only the extensions are different.  Creating The HPJ File  Creating Source Files
Page 2 of 20 Generate


Creating the HPJ File

Insert a semicolon (;) to add comments in the HPJ file. The compiler ignores any text following a semicolon to the end of the line. Comments record information about the various parts of the file.		To create the HPJ file, use either a word processor that saves files in ASCII or an ASCII editor.  Help project files can have as many as nine different sections (see Optional Sections). Section names must be located inside square brackets like this: [SECTION NAME] However, the HPJ file only requires a minimum of two sections to generate a Help file, as follows:  [OPTIONS] [FILES]
Page 3 of 20 Generate


Extension HPJ

Here is a typical file name for the HPJ file:

YourAPP.HPJ

 Note: The file naming convention must follow the MS-DOS file naming conventions. There can be up to eight alphanumeric characters followed by the HPJ extension.


Required Sections

	Section names must be enclosed in brackets. The two mandatory sections and suggested options are as follows:
	Section [OPTION]	Option N/A Title Warning Errorlog	Description Includes controls on how to build the Help file and information displayed during the build process Specifies the name of the application in the title bar area of the Help window Specifies the error-reporting level during the build Records all error messages encountered during the build process into a file specified in the HPJ file
Page 4 of 20 Generate


Required Sections Continued
Required Sections (Continued)

	Section [OPTION] [FILES]	Option Compress N/A	Description Sets the type of compression to use during the build process. There are three levels of compression. Specifies the source files (in RTF format) to use during the build process. There may be more than one file depending on the complexity of the Help system.
Page 5 of 20 Generate


Optional Sections

	In addition to the mandatory sections, the HPJ file can contain several other sections depending on the complexity of the Help system. The three most commonly used sections are:
For more information regarding these sections and others, refer to the compiler documentation.		Section  [BITMAPS] [MAP] [CONFIG]	Description Specifies the bitmaps, metafiles, and hypergraphic files to include during the build process. Equates context strings to arbitrary numbers. The numbers are used by programmers to activate various degrees of context sensitivity in the application. Allows the creation of specially named buttons, including Glossary.
Page 6 of 20 Generate


Specifies the bitmaps

Here is a typical bitmap section in the HPJ file:

[BITMAPS]

C:\help\mybmps\BUTT1.SHG

C:\help\mybmps\POPUP1.BMP

C:\help\mybmps\NEXT.WMF


Equates context strings

Mapping files are ASCII files that have the extension .HH. They contain definitions to equate context strings to arbitrary numbers that programmers use in their code to call Help topics. Here is a typical mapping section:

#define GENERAT_Generating_Help 54273

#define GENERAT_The_Help_Project_HP 54274

#define GENERAT_The_Source_Files 54275

#define GENERAT_The_Help_Compiler 54276


The Source File

		The source file contains the various Help topics used in the Help system. It must be formatted using Rich Text Format (RTF) in order for the Help compiler to recognize it.  Source files contain topic information along with control codes for each topic. These control codes determine how the Help system works. Control codes enable jumps from topic to topic, topic to popup, and linkage to topic groupings or buttons. Creating Source Files   Required Configuration  Optional Configurations
Page 7 of 20 Generate


Control Codes

Here is a typical control code for a topic that prints a metafile called CONTXT2:


Customizable footnotes

The word processor used should have the ability to create special symbols, such as + (plus sign), # (pound sign), $ (dollar sign), and K (uppercase K) for footnotes. Here is an example of a customizable footnote using K (uppercase K):


Creating Source Files

		To create a source file, follow these steps: 1. Use a word processor or text editor that formats text into Rich Text Format (RTF) and create a new file. Be sure that the word processor can produce customizable footnotes.  2. Enter the name of the first topic in the style and the format desired. 3. Enter a footnote using the pound sign (#) and enter the context string name as the footnote text. This will be used as the hypertext link to another topic.  4. Add a second footnote using the dollar sign ($) and enter the name of the topic as the footnote.  5. Create a hard page break and repeat steps one to four for the next topic. Continue adding topics. 6. Enter topic-specific information for each topic as required. 7. Create topic links for each of the topics created using the conventions for jumps and popups.
Page 8 of 20 Generate


Example Page; Help file example page
Example Page

Here is a typical page from a Help file:


Example: HPJ File

Here is a typical HPJ file:

[OPTIONS]

TITLE=Help Writing Help

WARNING=3

errorlog=errors.log

COMPRESS=FALSE

[CONFIG]

BrowseButtons()

[FILES]

hlpwrt.rtf

code.rtf

define.rtf

over.rtf

generate.rtf

[BITMAPS]

help\buildbmp\toc.bmp

help\buildbmp\about.bmp

help\buildbmp\about2.bmp

help\buildbmp\over.bmp

help\buildbmp\how.bmp

help\buildbmp\steps.bmp

help\buildbmp\tm.bmp


Required Configuration

Do not omit a topic title. Untitled topics can only display via a keyword (index) or by a browse sequence.		The source file must contain a topic title and a context string  to link the topic. Each topic is separated by a hard page break. The topic title ($) identifies the topic when the user performs a search in Help and the context string (#) provides the jump or popup to the information. For example, you create a topic named TROUBLESHOOTING and, it has the context string named TRBL_TROUBLE. If you want Help to reference this topic, specify TRBL_TROUBLE as the context string identifier for that page. Syntax for Coding Topics
Page 9 of 20 Generate


Topic Title

Here is a typical topic title:

Required Configuration


Context String

Here is a typical context string:


Optional Configurations

		The source file can contain several optional configurations to enhance how the user obtains information on the specific topic. It can include: Browse Buttons  Index Entries (Keywords)  Stand-Alone Topics  Required Configurations
Page 10 of 20 Generate


Browse Buttons

		Topics can display in a specified order. When using this option, there are two additional buttons (<< and >>) added to the Help Button Bar at the top of the Help Window. Click on these buttons (when available) to see groupings of related information. Creating Browse Sequences
Page 11 of 20 Generate


Index Entries (Keywords)

		Define keywords to enable the user to look up topics in Help. These keywords serve as index entries. Most Help systems use indexes. The Search list box has a maximum limit of 400 keywords. Coding the Search Button
Page 12 of 20 Generate


Stand Alone Topics
Stand-Alone Topics

		You can create topics without a topic name in Help. However, the only way to access the information is to link the topic to either a keyword (index entry) or to a browse sequence. Use stand-alone topics sparingly. If there is no name, there is no access to the topic via the Search button.
Page 13 of 20 Generate


The Help Compiler

		Use the Help compiler along with the HPJ file and related source file(s) to generate a Windows Help file. The Help compiler (HC31.EXE) is the executable file that compiles and generates a Windows .HLP file for your application. It has a data file containing error messages named HC31.ERR. Run the Help compiler at the MS-DOS command line in the appropriate Help directory. Enter the following command to generate a HLP file: C:>HC31.EXE YOURFILENAME.HPJ While executing, the program generates a series of dots to indicate that it is running. The more dots, the longer the build process. Error messages may also display during the build process, indicating problems in the source file or HPJ file. Files can take several minutes to over an hour to compile depending on their size and complexity.
Page 14 of 20 Generate


Help Compiler Continued
Help Compiler (Continued)

		If the error message indicates an out of memory message, try running the Help compiler for expanded memory (HCP.EXE). Enter this syntax at the command line: C:> HCP.EXE YOURFILE.HPJ Viewing the Help File  Troubleshooting Basics
Page 15 of 20 Generate


Viewing the Help File

		Once created, the .HLP file needs to be visually tested to make sure it works as expected. There are several ways to view Help, including viewing from: File Manager  An Icon  Windows Help Menu
Page 16 of 20 Generate


File Manager

		To run a Help file from the File Manager, first associate WINHELP.EXE to all .HLP files and then run the Help file. Follow theses steps: 1. Associate all .HLP files with the WINHELP.EXE file. 2. Select the File Manager from the appropriate Windows Group. 3. Select the correct path and subdirectory for the Help file. 4. Select your .HLP file using the keyboard or mouse. The .HLP file displays.
Page 17 of 20 Generate


Associate all .HLP files

When you associate a file, it identifies that file with a specific application. When selected, the file starts automatically. To associate .HLP files with WINHELP.EXE, follow these steps:

1.	Open the Windows File Manager.

2.	Select Associate from the File menu.

3.	Type HLP for the file extension and press TAB to the next field of the dialog box.

4.	Type WINHELP.EXE as the executable to associate files and select OK.


An Icon

		To execute the .HLP file from an icon in a Windows Program Group, follow these steps: 1. Associate all .HLP files  with WINHELP.EXE.  2. Create an MS-DOS batch file to execute your .HLP file. 3. Open the Program Manager and select New from the File menu. 4. Select Program Item and select OK. 5. Type the name of the HELP file and move to the next field. 6. Enter the correct path and file name for the batch file created. 7. Select OK to accept the default icon and program settings.
Page 18 of 20 Generate


Windows Help Menu

		To run a .HLP file from the Windows Help menu, follow these steps: 1. Open the Program Manager. 2. Select Contents from the Help menu. Windows Help opens and displays a new ribbon of menus. 3. Select Open from the Windows Help File menu. 4. Specify the path and file name for your .HLP file and press OK. Your .HLP file opens for viewing.
Page 19 of 20 Generate


Optional Files

Several third-party vendors offer converters to change bitmaps into metafiles.		The most common optional files are graphics (.BMP), metafiles (.WMF), and hypergraphics (.SHG). There are a variety of screen captures and graphics editors that use Windows BMP format. The developer's tool kit contains the Graphics Hotspot Editor which creates hypergraphics.
Page 20 of 20 Generate


Designing Help

		Designing Help consists of 4 phases. They listed in sequential order, as follows: Defining and Questioning  Generating and Refining  Finalizing  Implementing
Page 1 of 23 Design


Defining and Questioning

		Defining and questioning is the first phase in designing online Help. Think of online Help as a tool and design it for a specific user. In order to design it, know who the audience is and what they want to do. This process involves asking questions and trying to pin down the target audience. This breakdown of readers is critical to developing an appropriate Help system. It leads to establishing groupings of various types of audiences. Use the groupings, in turn, to further refining the definition. This process is cyclical and repetitive until the definitions and questions are answered. Here are a few questions to begin asking: Is the Help system going to help users get started using the application? Is the Help system going to improve user productivity? Is the Help system going to help users troubleshoot problems? What is the user's motivation to use the Help system? What is the user's background, job title, and training?
Page 2 of 23 Design


Defining and Questioning Continued
Defining and Questioning (Continued)

		Why You Should Define Your Audience  How to Design for Your Audience   Using an Audience - Task Matrix  Generating and Refining
Page 3 of 23 Design


Types of Audiences

User definition involves several categories that distinguish users and break them into groupings. Most common grouping is job title. Here is a typical job title breakdown of a target audience:

Job Title

Unskilled Operators (OP)

Trained Technicians (TT)

Software Developers (SW)

Hardware Developers(HW)

System Managers (SYS)

Manufacturing Managers (MFG)


Why You Should Define Your Audience

Like every documentation project, audience definition is mandatory. Without a well-defined audience, you will develop the wrong Help system. Users will fail to understand how to use the application, and you will fail at your responsibility to provide useful information. Worse yet, users will not use the application because the Help system is either too confusing or not directed to them.


How to Design for Your Audience

		Once you know the tasks your audience needs to perform and you have some breakdown of audience groupings, you can develop an Audience - Task Matrix.  Repeat this process several times until all tasks and groupings are refined. Eliminate unnecessary topics and add ones missed.
Page 4 of 23 Design


Example Audience - Task Matrix

Group target audiences with the tasks identified. Look for patterns. Here is a typical Audience/Task Matrix:

Job Title	Assembly	Test	QA
Unskilled Operators (OP)	X	X
Trained Technicians (TT)		X	X
Software Developers (SW)		X	X
Hardware Developers(HW)	X	X
System Managers (SYS)		X
Manufacturing Managers (MFG)	X


Using an Audience/Task Matrix
Using an Audience - Task Matrix

		The Audience - Task Matrix is a tool to help refine audience definition and the documentation required. Analyze the information gained in the Audience - Task Matrix. If a topic appears without a check, there may be a group missing from the matrix. If an audience group has no check, investigate why there are no topics for them.  Be sure to involve key players in this analysis, such as people from application development, user groups, product management, editing, and marketing. Repeat the analysis each time there is a new matrix. This analysis helps you decide how to breakdown the materials for the users. Clustering Ideas  Grouping Similar Tasks  Chunking Related Functions  Using a Topic Matrix with Groupings   Developing a Structured Outline
Page 5 of 23 Design


Generating and Refining

		The generating and refining phase of Help is a synergistic process that merges with the first phase of design. It is part of defining audience and questioning the facts. Repeat steps and forge on to new ones. Gain momentum and refine the development through each cycle. This process does not follow a set order. The sequence may bounce from defining audience to adding more tasks to the list and then start over again. Keep at it until all unclassified topics have a group or logical place in the Help system. Make sure all defined audiences have topic groupings associated with them. Recreate the audience - task matrix with new additional information. Analyze, generate, and refine these lists until groupings become obvious. This is not a fast process and should not be rushed.
Page 6 of 23 Design


Generating and Refining Continued
Generating and Refining (Continued)

		Clustering Ideas Grouping Similar Tasks Chunking Related Functions Using a Topic Matrix with Groupings   Developing a Structured Outline
Page 7 of 23 Design


Clustering Ideas

Clustering is the beginning of the organizational process. Whatever technique used for brainstorming ideas, the end result is to be able to cluster similar ideas together and make a list of them. Deciding which things go together and which do not is a changing process that goes through several iterations similar to listing topics.


Grouping Similar Tasks

Grouping similar tasks helps to organize topics. It is also the beginning of the overall organizational process of putting together a Help system. Arrange topics according to their functions and see if there are any relationships that develop. Over time, patterns evolve and groupings fall out and become apparent.


Chunking Related Functions

Read functional specifications (whenever possible) and become familiar with the software you are documenting. Accumulated knowledge helps you to see how the various functions of the specific application either work together or don't.

Determine which parts of the software are potential problems for the users. Things hard to understand now will be equally hard for the users to understand. Seek clarification.

Create a list of functions and begin grouping them into categories of importance and similarities. List confusing or complex functions. Offer solutions on how to improve the problems areas. Determine if menu groupings make sense. Arrange these ideas in chunks on paper. Try to get an overall feeling of the product.


Using a Matrix With Groupings

		Take the tasks from the Audience - Task Matrix. Cluster ideas, and similar task groupings and develop a new matrix. Match tasks with functional groupings to create a Task - Functions Matrix .  After completing this matrix there should be some true patterns emerging. Tasks versus functional groupings often indicate the types of documentation needed in a Help system. Does it point to reference or instructional materials? Are the tasks strongly associated with tutorial groupings? What is the overall pattern(s)? Use the patterns to further refine the Task- Audience Matrix until the Help topics become logically defined, and relationships appear systematically arranged. When they do, formalize this organization as a structured outline of the Help system. Developing a Structured Outline
Page 8 of 23 Design


Example of a Task - Functions Matrix

Here is a typical Task - Functions Matrix:

Tasks	Performed by?
Test boards	OP
Tag boards	OP
Test and diagnose boards	TT
Repair boards	TT, HW
Diagnose boards	TT, HW
Test and diagnose boards	HW
Test, diagnose, and repair boards	HW


Developing a Structured Outline

		The last step in generating and refining Help is to develop a structured outline. Unlike a traditional outline, the topics in the structured outline correspond to Help topics. Help topics are so modular that they are independent of other topics. Estimates of page counts and resources required should be easy at this point because the modules are so specific. Outlining should take little effort and helps you fill in any missing gaps. It is the next logical step in Help design.
Page 9 of 23 Design


Example: Structured Outline

Here is a typical structured outline for Help.

I Contents

Introduction

What Is HWH?

Audience

Prerequisites

Goals

Purpose

Requirements

Tooling Requirements

Hardware Requirements

Software Requirements


Finalizing

		Finalizing, the third phase of designing Help, involves the following: Planning the Architecture   Visualizing the Help Architecture   Planning Browse Sequences  Determining Preliminary Linkages  Determining the Degree of Context Sensitivity  Writing Module Summaries
Page 10 of 23 Design


Planning The Architecture

		Try to develop a conceptual model of the Help system. Once you know all of the topics and how they are grouped, this process can begin. Think through how the Help system will look and operate. Use brainstorming with other team members to get the overall look of the Help system. Draw pictures of how it will look. Make groupings of related topics and connect them with lines.
Page 11 of 23 Design


Visualizing The Application

		Use any software or technique to get the architecture on paper. Use a flow charting program, 3 x 5 cards, a drawing package, or try using an organizational chart software to diagram your system. Instead of names and organizations, fill in the boxes with topic names and show relationships visually. Fine tune any inconsistencies or add missing topics. Move topics that organizationally do not belong with a group. Look at the whole picture. Become aware of how each grouping and topic fit into the whole Help system. Look for duplications, omissions, and redundancies. Add topics and feel free to move topics around for better organization. This diagram becomes the working model of the Help system. It is the Help architecture. Remember, it is dynamic. Do not hesitate to change structures if it make sense to do so. Show the diagram to others and get their input. Modify where appropriate.
Page 12 of 23 Design


Planning Browse Sequences

		Display the working model on a wall or somewhere big enough to see it all. Try to decide where browse sequences would make sense. Figure out where they belong and have a sound reason for using them. Too many browse sequences can make the Help system seem redundant or confusing. Note the sequences on the working model. Look again to see if the sequences make sense from the user's point of view. Use colors (pencils or crayons) to distinguish various sequences. Show it to potential users and get their input. Make changes where appropriate.
Page 13 of 23 Design


Determining Preliminary Linkages

Using the Help system model, decide where topic jumps would make sense. Determine which topics should be linked together. Observe relationships of groupings. Mark these relationships (J=Jump and P=Popup) in the Help system model.


The Degree of Context Sensitivity

		Is the Help system going to use context-sensitive Help? If so, where, and to what degree? Here are some issues to discuss with the team regarding the application window: Menus  Ribbon Area  View Area  Status Bar  Icons  Dialog Boxes
Page 14 of 23 Design


Menus

Is there Help access from the Menu Bar? Will Help be for the menu commands or will it also include the sub-menu items as well? To what level will Help provide context-sensitivity? Can users get menu Help using both keyboard and mouse? Do they both need documenting? What procedures should be documented here?


Ribbon Area

Is there a ribbon area? Are there various fields where the user may want information? Can the software developers provide a connection to what is the current focus for that part of the ribbon? Which parts of the ribbon change after certain user actions? Are these changes clear or will they need extensive explaining? Do users know how to move throughout the various fields - forward and backward? Does this follow typical Windows conventions? What procedures should be documented here?


View Area

Is there a data portion or view area of the application window? Does the user need information about this area? Can the software developers provide a connection to that focus? Are there any scroll bars? Will all of the information be displayed or will the user need to be able to locate it? What procedures should be documented here?


Status Bar

Is there a status bar in the application window? Should the Help system document the various types of status messages the application may generate? If so, which ones and to what degree? Are there any procedures associated with messages on the status bar? Which ones? Do they need documenting?


Icons

Are there any icons in the application window? Can the user get Help from them? Should they be able to get Help from them? Are they documented in microhelp on the status bar or will they need to be explained? Are the icons customizable?


Dialog Boxes

Are there many dialog boxes in the application? How many? Should you document help for all dialog boxes? If not, which one should you document? Should you document Help for all input fields? Do the dialog boxes have more than 3 input fields? How confusing are the dialog boxes? Do the dialog boxes have Help buttons? Will this be enough Help for the user? How many topics are associated with each dialog box? Which topics to which dialog boxes?


Writing Module Summaries

Headline: Summary: Exhibit: Notes:		Write a three - four sentence module description about each topic. Nutshell the information about the topic. Leave out extra words. Be concise. Think about how it relates to other topics and how they might link together. Look at the list of preliminary links on the model Help system. Include ideas on what graphic, drawing, chart, or screen capture may help explain the concept. Write a summary for each topic in the Help system. Allow enough time to complete this task. Estimating time should be easy if the modules are refined to small enough units. Do not hurry. This is the essence of the Help documentation.
Page 15 of 23 Design


Example of Module Description

Here is a typical template for a module summary:

Headline = Popup:  Structuring Process

Summary:

Organizing Source Files

You need to determine how you are going to organize your Help source files when you begin to develop Help. This is an individualistic thing, but the main idea is to organize. You may want to have bitmaps in a separate directory away from the topic source files. You may also want the Help Compiler files in a different place. Organize your sources and be consistent.

Exhibit: MAKE THIS INTO A TABLE

Organizing Tools    To generate Help, you use several different tools and utilities. Know where they are and how to use them.

Determining How Many Files

Decide how many source files you will have and how they will be linked in the HPJ file.

Notes: Use new book formats to design for the screen display. See the style guide for details. Expand the question section.


Implementing

		The final phase of designing online Help is implementing. Implementing the Help system involves the following: Structuring Process  Formalizing Help Conventions   Coordinating Tasks
Page 16 of 23 Design


Structuring Process

The structuring process involves these activities:

Activity	Description
Organizing Source Files	You need to determine how you are going to organize the Help source files when you begin to develop Help. This is an individualistic thing, but the main idea is to organize. You may want to have graphics in a separate directory away from the topic source files. You may also want the Help compiler files in a different place. Organize the sources and be consistent.
Organizing Tools	To generate Help, you use several different tools and utilities. Know where they are and how to use them. Organize them to be easy to find and use.
Determining How Many Files	Standardize how to perform the mechanics of Help. Decide how many source files there will be and how they will be linked and added in the HPJ file.


Formalizing Help Conventions

	Decide which conventions to use, be consistent, and use the same conventions throughout the Help system. Here is what to consider:
	Item Footnoting    Naming and Numbering Navigating	Description Label footnotes with the title first and then the context string. This allows you to see the title of the topic first and then the context string second. When viewing footnotes, the context strings appear clearly with their respective titles. Try to distinguish commands, procedures, and definitions. Name objects using prefixes. Number consistently  Help users navigate through the Help system. Number page locations or show flow charts of how this portion of Help works.
Page 17 of 23 Design


Formalizing Conventions Continued
Formalizing Conventions (Continued)

	Item Style  Mapping	Description Develop a style guide for the Help system. Include a terminology list, use of numbering, and design templates for the Help source files. Include stylistic descriptions of screen layout and design for Help. Describe mapping techniques for future reference. Engineers will want some input. Be sure to consult with them.
Page 18 of 23 Design


Footnoting Conventions

Here is a typical footnote:


Naming Conventions

Use prefixes as part of the context string name. Prefixes allow searching for all instances of that string to extract specific information. Here are some approaches to naming objects using prefixes:

Commands

CMD_YOUR_COMMAND

Procedures

PROC_YOUR_PROCEDURES

Others

APP_PROC_NAMINGHELPTOPICS.

 Note: Whatever naming conventions you use, be careful of typos. The longer the name, the greater the chance for a syntax error during the build process.


Numbering Pages

Users get lost in hypertext topics easily. Here is one example of how numbering locations can help users navigate:

[File Menu 1 of 12]

Place a label (page number) on each topic in a given grouping. The user knows that they are viewing information on the first File menu command and that there are 12 other related topics. (This would also be a logical place for a browse sequence. Link the 12 commands together.) Explore other ways of helping users find their way around the Help system.


Navigating With Charts

Users find maps helpful if they are not too complex. Here is an example of a chart that illustrates the Help for a specific grouping of topics:


Screen Conventions

Include details of placement and size of topic titles, page numbers, topic text, and other references.

Be sure to leave a large amount of white space around the border of the screen because all video displays are not the same. Research appropriate sources for screen design and online displays.


Numbering Conventions

Here is a typical example of how to number a browse sequence:

Command:0010

Command:0020

Command:0030

In this example, Command is the name of the special group linked together (such as a series of menu commands) and the numbers are incremented by ten (allowing for additions during the project).

In the second example, a new menu command is added. It belongs between the first and second command. It looks like this:

Command:0010

Command:0015 (New command added without renumbering all the rest)

Command:0020

Command:0030


Mapping Conventions

		Mapping links of Help topics to the software in the application. Mapping can occur in either the HPJ file or in the .HH file. Check with the software engineers about which way to do this. Come to an agreement on who will perform this task and how.  Mapping is equating your context strings to an arbitrary number. The software developer uses this information to link your Help to their program. Here is a typical mapping method in the HPJ file: [Map] FIRST_STRING  ;0100 ;1st set of comments SECOND_STRING ;0101 ;2nd set of comments THIRD_STRING  ;0102 ;3rd set of comments
Page 19 of 23 Design


Mapping Conventions Continued
Mapping Conventions (Continued)

		Here is a typical mapping method in the HH file: #define GENERAT_Generating_Help 00100 #define GENERAT_The_Help_Project_HP 00110 #define GENERAT_The_Source_File_s 00120 #define GENERAT_The_Help_Compiler 00130 Note: Leading zeros are significant.
Page 20 of 23 Design


Coordinating Tasks

		The writing effort and development of the Help system occurs at this phase of design. It includes (in sequence) the following topics: Writing Help Topics Generating Help Files Testing Help Files Debugging Help Files Editing Help Topics Technical Reviewing Of Help Topics Coordinating with Base Levels
Page 21 of 23 Design


Writing Help Topics

Perform this task after generating the Help shell. Topic summaries should make writing Help modules a easy task. If summaries are clear and concise, it should not be difficult to code and generate a functional .HLP file. Most of the thinking has already occurred, and this part becomes more a mechanical process. Copy the summaries into the working Help system shell. Add details where required and place exhibits (including graphics) where specified. Supplement notes on examples with solid information and fill in the missing points and details. Save and verify information on a regular basis. Compile Help and check often to ensure accuracy and that the Help system functions and displays as expected.


Generating Help Files

After you generate some topic files, running the compiler should be easy. Try to generate a working shell of the entire Help system, including all of the topics. You may want to automate the process using BATCH files to call the Help compiler and run the build process. The end result is a help file YOURAPP.HLP.


BATCH File Example

Here is a typical BATCH file:

HC31 YOURFILE.HPJ

This calls the Help compiler to run on the HPJ file named YOURFILE.HPJ which contains the correct build information.


Testing Help Files

		After generating a .HLP file, verify that it works correctly. This process involves manually running the Help file as a user would. View each topic, jump, and popup to be sure that there are no broken links or graphics problems. Record all instances of problems. Use the debugging methods as outlined in the troubleshooting  portion of this Help system.
Page 22 of 23 Design


Debugging Help Files

		When you run the Help compiler, it lists error messages associated with the build process. These indicate problems in the Help file that need correcting. Record the messages and look them up in the source documentation (if required). Follow the prescribed techniques on troubleshooting.
Page 23 of 23 Design


Editing Help Topics

Editing Help files could involve another person. Depending on circumstances, there may be a formal editing process. This is often incorporated with the technical review process to save time.

Editing ensures that you follow the styles and conventions for the Help system as formally spelled out earlier in the design process. It also ensures correct use of language and grammar.

If you edit your own work, put it down for a few days (if possible) before going back to review the material. This provides a fresh perspective and allows you to discover problems missed. Try editing backwards. This technique helps uncover things missed the first time around.


Technical Reviewing Help Topics

Verify the Help system for accuracy several times during its development. Insist that technical reviewers review for technical accuracy and not for grammar and punctuation. Reviewers should point out mistakes in Help and offer suggestions on how to correct the problem. Reviewers should be technical experts who can explain technical details as necessary.


Coordinating With Engineering Base Levels

Try to ensure that as engineering base levels change, the Help system keeps up with the most current software base level whenever possible. Strive to get the Help system tested with the application by users throughout the software development cycle. As the Help system goes through its final stages, coordinate the tasks with various individuals. Hand-out the latest Help version to the right people, set up review schedules, and have Help review meetings. Keep everyone informed of progress and problems encountered.


Tracking Info
Tracking Info'

		Creating online Help topics is the easy part of online Help, especially using a Help authoring tool. However, keeping track of all the information coded into the Help system is a formidable task. Establishing a method to recall information makes it easier to maintain, debug, and test the Help system. Tracking Info' Help topics include: Tracking Criteria  Methods of Tracking  Archiving Information
Page 1 of 4 Track


What to Track
Tracking Criteria (What to Track)

		Keeping track of information requires good organization because there is so much information hard coded into the topic files. Tracking can be very time consuming. (This becomes apparent while trying to meet deliverables on time.) It is also an individualistic thing. Information organization is different for each person. However, there are some basic information to track, as follows: Topic Names and Associated Links  Context Strings for Topics  Context Strings for Popups  Names of Graphics files Used  Mapping Information  Source File Names and Locations  Browse Sequences  Archiving Info
Page 2 of 4 Track


Topic Names and Associated Links

Tracking topics that call a specific jump or popup is critical in maintaining the Help system. Having this information readily available saves time and trouble during edits and updates.


Context Strings for Topics

Topics and related context strings tend to change during the software development cycle. Knowing the links associated with specific topics makes moving, copying, and deleting topics much easier. Having a current listing of this information makes editing and changing the Help system easier.


Context Strings for Popups

Tracking topics that call specific popups is equally important in maintaining a Help system. It is useful when moving or deleting a popup. Failure to track this data can create errors during the build process.


Names of Bitmaps Used

If the Help system uses graphics, know their file names, the source files they are in, and the topic that calls them. This becomes more important as the number of images increases in the Help system.


Mapping Information

Decide with software developers who is going to update the mapping information for the Help system. Work closely and try to avoid changing numbers for specific topics once you have shared mapping numbers with developers. Your changes impact their coding as well as your own. As a general rule, hand out mapping equivalents when you are reasonably sure that the user interface (UI) is stable.

Note: Remember that it is OK to add new numbers to the mapping section of the HPJ file. Just be sure to update the software developers as to your changes to ensure that they add them to their code.


Source File Names and Locations

Know the names and locations of all source files used in building your Help system, including bitmaps and metafiles. This information should be accurately recorded in the HPJ file.


Tracking Browse Sequences

Browse sequences can contain a special name as well as a numbering sequence for a designated grouping, especially in a complex Help system. Record all names and browse numbers related to each individual grouping. This information is readily available if source files are saved in ASCII format. All footnote information appears at the end of the hardcopy printout.


Methods of Tracking

		There are any number of ways to track information. The tracking method is more important when more than one writer is working on the same Help system, or if the files are translated. If everyone uses the same method, information will be easier to track. Remember that it is important to be consistent and when possible, use the same repository for your information.  Here are a few methods you can use to track information: ASCII Text File  Fastest Method  Spreadsheets  Word Processor
Page 3 of 4 Track


Word Processor

You can use a word processor to keep track of the Help system. Most offer multiple columns or the use of tables.


Spreadsheets

Spreadsheets enable you to arrange large numbers of columns and rows of Help project information. Spreadsheets can definitely track Help information. If time and money are considerations, spreadsheets also require that you purchase additional software and learn how to use it.


ASCII Text File

Any text editor can generate the type of lists Help systems require. MS-DOS Version 5.0 and greater includes the MS-DOS Editor.


Fastest Method

One of the easiest methods is to use source file hardcopy to track Help information. It is faster than the other methods and uses current versions of the Help system hard copies. It is not a formal tracking method, but it provides data during the development process.

  To create hard copies, follow these steps:

1.	Save source files as an ASCII text file (TXT).

2.	Print source files as ASCII text files. Hidden text will be included.

Topics appear first followed by the footnote information containing the context strings, topic names, browse sequences (if any), and keywords. When the Help system is complete, formalize the tracking method using any method of choice.


Archiving Information

		When the project is complete, you must be prepared to hand off the deliverables and store and record the sources for future use. Archiving methods much like tracking methods, are individualistic.  Here is a list of recommended archival data: Hard copies of Source Files  Floppy Backups of the data  Path and Directory Structures Used  Lists of All Context Strings Per File  Lists of All Bitmaps Used Per File  List of Mapping Numbers  List of Browse Sequences
Page 4 of 4 Track


Hard Copies of Source Files

Because it is hard to know who will need source files in the future, assume that others will use these files.

Print hard copies of all source files used to generate the Help system. Be sure to print hidden text and include pagination (when possible). Numbering pages makes it easier to locate topics and jumps. Place printed documents into a binder arranged in a logical fashion. You may want to use colored paper to indicate new files or to separate different information.


Paginate When Possible

Some authoring tools do not allow pagination in their required templates. RoboHelp 2 is a good example. When this happens, enter page numbers manually for future reference.


Floppy Backups

Include electronic copies of all source files (including bitmaps, metafiles, and icons) and place floppies in the binder with the printed materials.


Path and Directory Structures Used

Include a summary of the process and the names of directories and sub-directories used to build the Help system. Include this sheet in front of the documents in the binder.


Lists of All Context Strings Per File

It is helpful to have a list of all context strings used in a specific source file. Some utilities enable you to extract this data from source files in a chronological sequence; others use word processing macros.


Lists of All Graphics Used Per File

It is helpful to have a listing of all graphics used in a specific source file. Some utilities enable you to extract this data from source files in a chronological sequence; others use word processing macros.


List of Mapping Numbers

Print a copy of the HPJ file and include it in your binder. It should contain listings of mapping used in generating your Help system.


Troubleshooting Basics

		There are several errors that can take place when you build Help files. Errors can occur in several places, including: The Help file (.HLP) itself usually in the way things display after the build The Help Project File (.HPJ) file - usually omissions create problems The source file(s) - where a variety of problems occur Errors have degrees of severity. Know what they are before trying troubleshooting. Familiarize yourself with these areas first: Before You Begin What Do You Need To Know?  The Troubleshooting Process
Page 1 of 11 Trouble


What Do You Need To Know?

		Part of the troubleshooting process is trying to figure out where the problem occurs. Generally, there are 5 basic types of errors, as follows: 1. Syntax Errors  2. Reported Formatting Errors  3. Visually Detected Errors  4. Duplicate or Lost File Errors  5. Miscellaneous Errors  Creating the HPJ File  Fixing Hidden Page Breaks  Fixing Hidden Paragraph Errors  Fixing Non-Scrolling Region Errors
Page 2 of 11 Trouble


Degrees of Severity

The Help compiler reports three levels of severity. They are:

Level	Description
Warning = 1	The compiler only reports the most severe warnings. You can use this level when you are in a hurry and know that most of the source files are clean of mistakes.
Warning = 2	The compiler reports severe and less serious warnings. If you use this setting, you may as well report all errors.
Warning = 3	The compiler reports all warnings. Use this level to clean up your source files. (Use this for testing.)


Before You Begin

Most mistakes appear during the build process. Open the .HPJ file and make sure that the warning level is set to three in the Options section. To report all errors that occur in the build process, enter:

[OPTIONS]

WARNING=3

To isolate where the error occurs, record the errors during the build process. Again, open the HPJ file and add the error log option, as follows:

[OPTIONS]

ERRORLOG=YOURFILE.LOG (or) YOURFILE.TXT

This sequence produces a readable ASCII file containing the error messages reported by the compiler during the build process.


Troubleshooting Process

		During the troubleshooting process, you isolate the problem, record errors, and ask a series of questions: Record The Error  Where Does This Error Occur?  Where Should You Look To Isolate This Error?  What Should You Try To Resolve This Error?
Page 3 of 11 Trouble


Record The Error

Be sure that you identify the error message exactly and, if possible, its number. Record this information so that you can refer to it.


Where Does This Error Occur?

Determine where the error occurred. Did it happen during the build sequence? If so, during which sequence? Was it visually detected? On which screen did it occur? Know where you saw the error and isolate the possibilities.


Where Should You Look To Isolate This Error?

Eliminate where not to look for the problem. Try to determine where to find this error. Was it in the source file? If so, in which topic? Was it a problem with a graphic? If so, which one and in which topic(s)?


What Should You Try To Resolve This Error?

Think of possible solutions to resolve the problem. Keep a reference handy with the compiler error messages. Read the description of the reported error. Once the problem is isolated, what is required to correct it? Is it a syntax error? Look for incorrect syntax on the specified topic. Does the problem involve hidden text? Look at the syntax used for the topic. Be sure hidden text is turned on when you view your source file. Try to think of a logical approach to the problem. Take it one step at a time.


Syntax Errors

		Learn to recognize some of the most common syntax errors and how to correct them. Here are some likely syntax errors: Error Reported Context String Yourstring Already Used (4011 )  Invalid Context String YOURSTRING (4031 )  Unresolved Jump or Popup YOURSTRING (4113 )  Browse Sequence Already Defined (4312 )
Page 4 of 11 Trouble


Context String Yourstring Already Used

Context String Yourstring Already Used (4011)

Problem:

You have duplicated the link name in another topic. Only the first link will be active. The duplicate will not connect to its topic. Remember that each topic must have a unique identifier.

Solution:

To correct the problem, change the name of the offending topic link. Make it unique.


Invalid Context String YOURSTRING

Invalid Context String YOURSTRING (4031)

Problem:

There is something wrong with the topic context string (link) name. Your link will not be active.

Solution:

Check for correct syntax in the context string and be sure there are no typos, such as blank spaces.

Context_String <-INVALIDSPACE

Delete the spaces.

Context_StringNOSPACE


Unresolved Jump or Popup YOURSTRING

Unresolved Jump or Popup YOURSTRING (4113)

Problem:

The context string used to jump or popup to this topic is nonexistent. It may be pointing to a topic not included in the build. It renders the link broken, and your jump/popup will not work.

Solution:

Search for the topic and check the name of the link. Be sure the topic is included in the build. It is possible to create a topic without linking it. Verify that a hypertext link activates the specified topic. If not, fix the problem, recompile the Help file, and test again.


Browse Sequence Already Defined

Browse Sequence Already Defined (4312)

Problem:

The browse sequence name or number is a duplicate. The last browse name or number will not be included in the sequence.

Solution:

Locate the second browse sequence and change either the name or number to a unique value.


Reported Formatting Errors

		Sometimes the build process indicates formatting problems. This usually means the problem is in your source file(s). Here are some common types of formatting errors: Error Reported Hidden Page Break (4733)  Hidden Paragraph (4753)  Non Scrolling Region Defined After Scrolling Region (4792)
Page 5 of 11 Trouble


Hidden Page Break

Hidden Page Break (4733)

Problem:

A page break is mixed up with hidden text. The page break will not separate two topics. This causes strange screen displays of text wrapping in the wrong places and topics run together.

Solution:

Find the hidden page break and make it visible with your word processor. Recompile the Help file and test again.


Fixing Hidden Page Break Errors

		To fix a hidden page break, follow these steps: 1.  Open the source file and locate the offending topic. 2. Highlight the last paragraph tag or page break indicator. 3. Check the characteristics for that symbol and see if it is defined as hidden text.  4. Render hidden symbols unhidden, save, and recompile the Help file. 5. Verify that the problem is corrected.
Page 6 of 11 Trouble


Hidden Paragraph

Hidden Paragraph (4753)

Problem:

A paragraph marker is mixed up in hidden text. This causes bazaar screen output in the Help File.

Solution:

Locate the hidden paragraph tags in the source files and render them as visible characters with your word processor. Recompile and test again.


Fixing Hidden Paragraph Errors

		To fix a hidden paragraph, follow these steps: 1.  Open the source file and locate the offending topic. 2. Highlight a paragraph tag located near hidden text on the page. 3. Check the characteristics for the paragraph symbol to see if it is defined as hidden text.  4. Render hidden paragraph symbols unhidden, save, and recompile the Help file. 5. View the topic to ensure that the problem is fixed.
Page 7 of 11 Trouble


Non Scrolling Region Defined After Scrolling Region

Non-Scrolling Region Defined After Scrolling Region (4792)

Problem:

A paragraph linked to scroll under a topic title is not the first paragraph under the title.

Solution:

Locate the offending paragraph in the source file and render it as a visible character.


Fixing Non-Scrolling Region Errors

		To fix this error, follow these steps: 1.  Open the source file and locate the offending page. 2. Highlight the topic for that page. 3. Check the paragraph characteristics (in Word for Windows) to see if the topic is associated with Keep With Next. 4. Locate the next paragraph and repeat step 3. Deselect any other paragraphs that are associated with Keep With Next. 5. Save edits and recompile the Help file. 6. View the Help file to ensure that the problem is fixed.
Page 8 of 11 Trouble


Visually Detected Errors

		Do not work on a variety of help topics or files before you verify the Help file, especially if errors are extensive for a given topic. Locating one problem is much easier than trying to isolate several in various parts of the Help system. Some formatting and display problems do not show up during the build process. The Help compiler does not indicate any errors. Consequently, you need to check your Help file after each build.  Here are two common unreported errors that occur: >>Untitled Topic<<  Unable to print picture
Page 9 of 11 Trouble


Untitled Topic
>>Untitled Topic<<

Problem:

This message appears in the History list box  or in the Search list box . There is no identified for this topic (no $ topic name given). You can only access this topic by double clicking or Tab to it and press Enter.

Solution:

Determine the topic and give it a title using the correct syntax ($) in the source file. Recompile and view the file to ensure that the problem is fixed.


History List Box

Here is a typical example of the >>Untitled Topic<< message using the History button:


Unable to print picture

Unable to print picture (graphic)

Problem:

This message is usually associated with a missing file error message. It appears on the Help screen where you want to show a picture. You find these mistakes when testing the most recent Help build.

Solution:

Check to see if the graphic is entered in the HPJ file and in the source file. Also look for incorrect spelling of the graphic in both places.


Search List Box

Here is a typical example of the >>Untitled Topic<< message using the Search button:


Duplicate or Lost File Errors

		Some errors result from duplicating file names or by trying to use a corrupt RTF file. Occasionally errors result when moving links. Here are some typical errors of these types: File YOURHELP.RTF is not a valid RTF topic file (4616)  Footnote text missing (4231)  Bitmap name YOURBMP.BMP duplicated (1513)
Page 10 of 11 Trouble


File YOURHELP.RTF is not a valid RTF topic file

File YOURHELP.RTF is not a valid RTF topic file (4616)

Problem:

The RTF file was saved accidentally in a document format. The compiler needs RTF format.

Solution:

Open the source file and resave the file in RTF format. Rerun the build using the new file. View the results to ensure that the problem is fixed.


Footnote text missing
Footnote text missing (4231)

Problem:

You have removed footnote information causing this error. It probably occurred during some edits to that page and footnotes were inadvertently moved or erased.

Solution:

Re-enter the correct footnotes for the topic. Rerun the build using the corrected version of the file. View to ensure that the problem is fixed.


Bitmap name YOURBMP.BMP duplicated

Bitmap name YOURBMP.BMP duplicated (1513)

Problem:

There are two different graphics with the same file name in the source file, or in another source file mentioned in the HPJ file.

Solution:

Locate the double bitmap (or metafile) in the source file and rename it. Also change the file name accordingly in the HPJ file. Rerun the build and view the results to ensure that the problem is fixed.


Miscellaneous Errors

		There are a few miscellaneous errors that are common. They are as follows: Not Enough Memory to Build Help File (5059)  Using Old Key Phrase Table (5098)  File YOURHELP.HLP Is Not Created (5035)
Page 11 of 11 Trouble


Not Enough Memory

Not Enough Memory (5059)

Problem:

The PC runs out of lower memory during the compilation. Typically this happens when the Help system either uses a lot of graphics or uses large bitmaps.

Solution:

Check the number and size of device drivers in the CONFIG.SYS file. Comment out any unused devices, save, and reboot the PC. Try and free up as much of lower memory as possible. An optimal number to strive for is approximately 550, 000 KBs. That should run most build processes.

If this does not work, try running the compiler HCP.EXE which allows you to use high memory (extended and expanded). Consult the appropriate documentation for more information regarding this compiler.


Using Old Key Phrase Table

Using Old Key Phrase Table (5098)

Problem:

This problem shows up when the compiler is set to maximum compression. The Help compiler creates a new table with each compressed build unless an older version exists.

Solution:

Delete the .PH file before running the build. This will make the build process run longer than if using an old table.


File YOURHELP.HLP Is Not Created

File YOURHELP.HLP Is Not Created (5035)

Problem:

The Help compiler did not create a .HLP file.

Solution:

Check to see if there are any topics to compile by checking to see if the build expression is set to FALSE for all topics. Change accordingly.


Thinking Smart
Thinking (Working) Smart

		There are several ways to be more productive using a word processor, especially if it has all of the features mentioned. Here are some useful tips on working smarter: Bookmarking Topics Printing in ASCII  Using Drag and Drop  Using Glossaries   Using Macros  Using Outlining  Using Styles and Templates  Using the Time and Date Stamp  Saving Work
Page 1 of 2 Think Smart


Bookmarking Topics

		A bookmark is a way of marking a topic for finding it quickly in the future. This is helpful in flagging main groups of topics  in the source file. It allows the author to search and locate various parts of a large source file.
Page 2 of 2 Think Smart


Example: Bookmarking

Here is a typical set of bookmarks:


Printing in ASCII

You can save a lot of paper and time by saving source files as ASCII text and then by printing them. This reduces pages by a substantial number. ASCII files print topics at the beginning and all footnote information at the end. This makes tracking information easy by providing an informal method.


Using Outlining

Use the outline feature to expand and collapse topic headings and to move large blocks of text from one point to another. Moving using this feature is often easier than using cut and paste. Not every word processor offers this feature.


Using Drag and Drop

The drag and drop feature allows the movement of text or graphics using the mouse. It is a fast, efficient method of editing short phrases of text. Consider using it to save time and retyping. This feature is ideal for moving text short distances. Not every word processor offers this feature.


Using Styles

A style is a stored group of formats in a word processing document. Styles have these advantages:

They save time formatting documents.

They are easy to create and use.

They ensure consistency.

They can be easily changed and globally changed.

They can be shared by other writers in document templates.

You can save large groups of styles as document templates. The templates could contain all the formatting for online Help


Using The Time and Date Stamp

You may want to consider using the Time and Date stamp for source files. This is especially true when sharing files with other writers or when trying to determine if you have the latest version of the source files.


Using Glossaries

Use the glossary feature to eliminate typing large repetitive blocks of text (boilerplate text) or to insert frequently used graphics. Glossaries can also help format screen layouts.

Use glossaries for:

Typing standard clauses

Entering unusually formatted text

Screen layout (i.e.; Related Topics heading, for example:)

Most professional word processors have this feature.


Using Macros

A macro is a set of commands and operations that can run complex WP tasks using a single command. Most macro languages allow you to create these operations by recording your example.

Use macros for:

Automating saving a document and then saving the document as an RTF file

Changing a command

Selecting a frequently used dialog box

For more information on macros, refer to the appropriate word processing documentation.


Saving Work

Create and save the source files in both document and RTF formats. If one is damaged, the other serves as an instant backup.

How often to save your WP files is a personal matter. As a general rule, if you have worked more than 10 minutes and your work is important, then save every 10 minutes. Use auto save if available, and if there is plenty of disk space.